aliases:
- Using Obsidian URI
- Advanced topics/Using obsidian URI
- Concepts/Obsidian URI
Obsidian URI is a custom URI protocol supported by Obsidian that lets you trigger various actions, such as opening a note or creating a note. Obsidian URI enables automation and cross-app workflows.
Obsidian URIs use the following format:
obsidian://action?param1=value¶m2=value
The action
parameter is the action that you would like to perform. Available actions include:
open
to open a note.new
to create or add to an existing note.daily
to create or open your daily note.search
to open a search.Ensure that your values are properly URI encoded. For example, forward slash characters /
must be encoded as %2F
and space characters must be encoded as %20
.
This is especially important because an improperly encoded "reserved" character may break the interpretation of the URI. See here for details.
The open
action opens an Obsidian vault, or opens a file within that vault.
obsidian://open?vault=my%20vault
my vault
. If the vault is already open, focus on the window.obsidian://open?vault=ef6ca3e3b524d22f
ef6ca3e3b524d22f
.obsidian://open?vault=my%20vault&file=my%20note
my note.md
in the vault my vault
, assuming the file exists.obsidian://open?path=%2Fhome%2Fuser%2Fmy%20vault%2Fpath%2Fto%2Fmy%20note
/home/user/my vault/path/to/my note
. Then, the rest of the path is passed to the file
parameter. For example, if a vault exists at /home/user/my vault
, then this would be equivalent to file
parameter set to path/to/my note
.With proper URI encoding, you can navigate to a heading or block within a note. Note%23Heading
would navigate to the heading called "Heading", whereas Note%23%5EBlock
would navigate to the block called "Block".
vault
can be either the vault name or the vault ID[1].file
can be either a file name, or a path from the vault root to the specified file. If the file extension is md
, the extension can be omitted.path
an absolute file system path to a file.
vault
and file
.file
parameter.prepend
will add to the top of the file and attempt to merge properties.append
will add to the end of the file and also attempt to merge properties.The new
action, creates a new note in the vault, optionally with some content.
obsidian://new?vault=my%20vault&name=my%20note
my vault
, and creates a new note called my note
.obsidian://new?vault=my%20vault&path=path%2Fto%2Fmy%20note
my vault
, and creates a new note at path/to/my note
.vault
can be either the vault name, or the vault ID[1-1]. Same as action open
.name
the file name to be created. If this is specified, the file location will be chosen based on your "Default location for new notes" preferences.file
a vault absolute path, including the name. Will override name
if specified.path
a globally absolute path. Works similar to the path
option in the open
action, which will override both vault
and file
.content
(optional) the contents of the note.clipboard
(optional) use of the contents of the clipboard instead of specifying content
.silent
(optional) include this parameter if you don't want to open the new note.append
(optional) include this parameter to append to an existing file if one exists.overwrite
(optional) overwrite an existing file if one exists, but only if append
isn't set.x-success
(optional) see Use x-callback-url parameters.The daily
action creates or opens your daily note. The Daily notes plugin must be enabled.
obsidian://daily?vault=my%20vault
my vault
, and creates or opens the daily note.The daily
action accepts the same parameters as the new
action.
This Obsidian URI action is to be used with Hook.
obsidian://hook-get-address
vault
(optional) can be either the vault name, or the vault ID[1-3]. If not provided, the current or last focused vault will be used.x-success
(optional) see Use x-callback-url parameters.x-error
(optional) see Use x-callback-url parameters.If x-success
is defined, this API will use it as the x-callback-url. Otherwise, it will copy a Markdown link of the current focused note to the clipboard, as an obsidian://open
URL.
Some endpoints will accept the x-callback-url parameters x-success
and x-error
. When it's provided, Obsidian will provide the following to the x-success
callback:
name
the name of the file, without the file extension.url
the obsidian://
URI for this file.file
(desktop only) the file://
URL for this file.For example, if Obsidian receives
obsidian://.....x-success=myapp://x-callback-url
, the response would be myapp://x-callback-url?name=...&url=obsidian%3A%2F%2Fopen...&file=file%3A%2F%2F...
In addition to the formats above, there are two more "shorthand" formats available to open vaults and files:
obsidian://vault/my vault/my note
is equivalent to obsidian://open?vault=my%20vault&file=my%20note
.obsidian:///absolute/path/to/my note
is equivalent to obsidian://open?path=%2Fabsolute%2Fpath%2Fto%2Fmy%20note
.On Windows and macOS, running the app once should be sufficient to register the Obsidian URI protocol on your computer.
On Linux, it is a much more involved process:
obsidian.desktop
file. See here for details.Exec
field as Exec=executable %u
. The %u
is used to pass the obsidian://
URIs to the app.Obsidian-x.y.z.AppImage --appimage-extract
. Then make sure the Exec
directive points to the unpacked executable.